---
title: Spec - howl.Regex
tags: spec
---
<div class="spec-group spec-group-1">

<h1 id="howl.regex">howl.Regex</h1>

<h4 id=".pattern-holds-the-regex-used-for-construction">.pattern holds the regex used for construction</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'foo(bar)'</span><span class="p">,</span><span class="w"> </span><span class="n">r</span><span class="p">(</span><span class="s1">'foo(bar)'</span><span class="p">).</span><span class="n">pattern</span></code></pre>


<h4 id=".capture_count-holds-the-number-of-captures-in-the-pattern">.capture_count holds the number of captures in the pattern</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="n">r</span><span class="p">(</span><span class="s1">'foo(bar) (\\w+)'</span><span class="p">).</span><span class="n">capture_count</span></code></pre>


<h4 id="r.is_instance(v)-returns-true-if-&lt;v&gt;-is-a-regex">r.is_instance(v) returns true if &lt;v&gt; is a regex</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">is_true</span><span class="w"> </span><span class="n">r</span><span class="p">.</span><span class="n">is_instance</span><span class="w"> </span><span class="n">r</span><span class="s1">'foo'</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">is_false</span><span class="w"> </span><span class="n">r</span><span class="p">.</span><span class="n">is_instance</span><span class="w"> </span><span class="s1">'foo'</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">is_false</span><span class="w"> </span><span class="n">r</span><span class="p">.</span><span class="n">is_instance</span><span class="w"> </span><span class="p">{}</span></code></pre>


<h4 id="escape(s)-returns-a-string-with-all-special-regular-expression-symbols-escaped">escape(s) returns a string with all special regular expression symbols escaped</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'a\\.b\\*c'</span><span class="p">,</span><span class="w"> </span><span class="n">r</span><span class="p">.</span><span class="n">escape</span><span class="w"> </span><span class="s1">'a.b*c'</span></code></pre>


<h4 id="tostring(regex)-returns-the-pattern">tostring(regex) returns the pattern</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'\\s*(foo)'</span><span class="p">,</span><span class="w"> </span><span class="nb">tostring</span><span class="w"> </span><span class="n">r</span><span class="s1">'\\s*(foo)'</span></code></pre>

<div class="spec-group spec-group-2">

<h3 id="(creation)">(creation)</h3>

<h4 id="raises-an-error-if-the-pattern-is-invalid">raises an error if the pattern is invalid</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">raises</span><span class="w"> </span><span class="s1">'regular expression'</span><span class="p">,</span><span class="w"> </span><span class="o">-&gt;</span><span class="w"> </span><span class="n">r</span><span class="s1">'?\\'</span></code></pre>


<h4 id="returns-a-regex-for-a-valid-pattern">returns a regex for a valid pattern</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">is_not_nil</span><span class="w"> </span><span class="n">r</span><span class="s1">'foo()\\d+'</span></code></pre>


<h4 id="accepts-a-regex-as-well">accepts a regex as well</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">is_not_nil</span><span class="w"> </span><span class="n">r</span><span class="w"> </span><span class="n">r</span><span class="s1">'foo()\\d+'</span></code></pre>


<h4 id="accepts-and-optional-table-of-compile-flags">accepts and optional table of compile flags</h4>

<pre class="highlight moonscript"><code><span class="n">reg</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">r</span><span class="w"> </span><span class="s1">'.'</span><span class="p">,</span><span class="w"> </span><span class="p">{</span><span class="n">r</span><span class="p">.</span><span class="n">DOTALL</span><span class="p">}</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">is_truthy</span><span class="w"> </span><span class="n">reg</span><span class="o">\</span><span class="n">match</span><span class="w"> </span><span class="s2">"\n"</span></code></pre>


<h4 id="accepts-and-optional-table-of-match-flags">accepts and optional table of match flags</h4>

<pre class="highlight moonscript"><code><span class="n">reg</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">r</span><span class="w"> </span><span class="s1">'x'</span><span class="p">,</span><span class="w"> </span><span class="kc">nil</span><span class="p">,</span><span class="w"> </span><span class="p">{</span><span class="n">r</span><span class="p">.</span><span class="n">MATCH_ANCHORED</span><span class="p">}</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">is_falsy</span><span class="w"> </span><span class="n">reg</span><span class="o">\</span><span class="n">match</span><span class="w"> </span><span class="s2">"ax"</span></code></pre>

</div>
<div class="spec-group spec-group-2">

<h2 id="match(string-[,-init])">match(string [, init])</h2>

<h4 id="returns-nil-if-the-pattern-does-not-match">returns nil if the pattern does not match</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">is_nil</span><span class="w"> </span><span class="n">r</span><span class="s1">'foo'</span><span class="o">\</span><span class="n">match</span><span class="w"> </span><span class="s1">'bar'</span></code></pre>

<div class="spec-group spec-group-3">

<h3 id="(with-no-captures-in-the-pattern)">(with no captures in the pattern)</h3>

<h4 id="returns-the-entire-match">returns the entire match</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'right'</span><span class="p">,</span><span class="w"> </span><span class="n">r</span><span class="s1">'ri\\S+'</span><span class="o">\</span><span class="n">match</span><span class="w"> </span><span class="s1">'red right hand'</span></code></pre>

</div>
<div class="spec-group spec-group-3">

<h3 id="(with-captures-in-the-pattern)">(with captures in the pattern)</h3>

<h4 id="returns-the-captured-values">returns the captured values</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="s1">'red'</span><span class="p">,</span><span class="w"> </span><span class="s1">'right'</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">r</span><span class="s1">'(r\\w+)\\s+(\\S+)'</span><span class="o">\</span><span class="n">match</span><span class="w"> </span><span class="s1">'red right hand'</span><span class="w"> </span><span class="p">}</span></code></pre>


<h4 id="empty-captures-are-returned-as-position-captures">empty captures are returned as position captures</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">4</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">r</span><span class="s1">'()red()'</span><span class="o">\</span><span class="n">match</span><span class="w"> </span><span class="s1">'red'</span><span class="w"> </span><span class="p">}</span></code></pre>


<h4 id="position-captures-are-character-based">position captures are character based</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">r</span><span class="s1">'å()ä()'</span><span class="o">\</span><span class="n">match</span><span class="w"> </span><span class="s1">'åäö'</span><span class="w"> </span><span class="p">}</span></code></pre>


<h4 id="return-non-matching-optional-captures-as-empty-strings">return non-matching optional captures as empty strings</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="s1">'1'</span><span class="p">,</span><span class="w"> </span><span class="s1">''</span><span class="p">,</span><span class="w"> </span><span class="s1">'2'</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">r</span><span class="s1">'(1)(\\w)?(2)'</span><span class="o">\</span><span class="n">match</span><span class="w"> </span><span class="s1">'12'</span><span class="w"> </span><span class="p">}</span></code></pre>

</div>
<div class="spec-group spec-group-3">

<h3 id="(when-init-is-specified)">(when init is specified)</h3>

<h4 id="matching-starts-from-the-init-position">matching starts from the init position</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'right'</span><span class="p">,</span><span class="w"> </span><span class="n">r</span><span class="s1">'r\\S+'</span><span class="o">\</span><span class="n">match</span><span class="w"> </span><span class="s1">'red right hand'</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="mi">6</span><span class="p">,</span><span class="w"> </span><span class="n">r</span><span class="s1">'r()\\S+'</span><span class="o">\</span><span class="n">match</span><span class="w"> </span><span class="s1">'red right hand'</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span></code></pre>


<h4 id="negative-values-counts-from-the-end">negative values counts from the end</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">equal</span><span class="w"> </span><span class="s1">'og'</span><span class="p">,</span><span class="w"> </span><span class="n">r</span><span class="s1">'o\\w'</span><span class="o">\</span><span class="n">match</span><span class="w"> </span><span class="s1">'top dog'</span><span class="p">,</span><span class="w"> </span><span class="o">-</span><span class="mi">2</span></code></pre>

</div>
</div>
<div class="spec-group spec-group-2">

<h2 id="find(s,-init)">find(s, init)</h2>

<h4 id="returns-nil-if-the-pattern-could-not-be-found-in-&lt;s&gt;">returns nil if the pattern could not be found in &lt;s&gt;</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">is_nil</span><span class="w"> </span><span class="n">r</span><span class="s1">'foo'</span><span class="o">\</span><span class="n">find</span><span class="w"> </span><span class="s1">'bar'</span></code></pre>


<h4 id="returns-the-indices-where-the-pattern-match-starts-and-end-if-found">returns the indices where the pattern match starts and end if found</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">r</span><span class="s1">'\\pL'</span><span class="o">\</span><span class="n">find</span><span class="w"> </span><span class="s1">'!äö'</span><span class="w"> </span><span class="p">}</span></code></pre>


<h4 id="returns-any-captures-after-the-indices">returns any captures after the indices</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="s1">'ä'</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">r</span><span class="s1">'(\\pL)'</span><span class="o">\</span><span class="n">find</span><span class="w"> </span><span class="s1">'!äö'</span><span class="w"> </span><span class="p">}</span></code></pre>


<h4 id="empty-captures-are-returned-as-position-captures">empty captures are returned as position captures</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">2</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">r</span><span class="s1">'\\pL()'</span><span class="o">\</span><span class="n">find</span><span class="w"> </span><span class="s1">'!äö'</span><span class="w"> </span><span class="p">}</span></code></pre>


<h4 id="starts-matching-after-init">starts matching after init</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="mi">3</span><span class="p">,</span><span class="w"> </span><span class="mi">5</span><span class="p">,</span><span class="w"> </span><span class="mi">6</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">r</span><span class="s1">'\\w+()'</span><span class="o">\</span><span class="n">find</span><span class="w"> </span><span class="s1">'12ab2'</span><span class="p">,</span><span class="w"> </span><span class="mi">3</span><span class="p">}</span></code></pre>

</div>
<div class="spec-group spec-group-2">

<h2 id="gmatch(s)">gmatch(s)</h2>

<h4 id="returns-no-matches-when-it-does-not-match">returns no matches when it does not match</h4>

<pre class="highlight moonscript"><code><span class="n">matches</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span><span class="n">m</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="n">m</span><span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="n">r</span><span class="s1">'\\d+'</span><span class="o">\</span><span class="n">gmatch</span><span class="w"> </span><span class="s1">'well hello there'</span><span class="p">]</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="p">{},</span><span class="w"> </span><span class="n">matches</span></code></pre>

<div class="spec-group spec-group-3">

<h3 id="(with-no-captures-in-the-pattern)">(with no captures in the pattern)</h3>

<h4 id="produces-each-consecutive-match-in-each-call">produces each consecutive match in each call</h4>

<pre class="highlight moonscript"><code><span class="n">matches</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span><span class="n">m</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="n">m</span><span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="n">r</span><span class="s1">'\\w+'</span><span class="o">\</span><span class="n">gmatch</span><span class="w"> </span><span class="s1">'well hello there'</span><span class="p">]</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="s1">'well'</span><span class="p">,</span><span class="w"> </span><span class="s1">'hello'</span><span class="p">,</span><span class="w"> </span><span class="s1">'there'</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="n">matches</span></code></pre>

</div>
<div class="spec-group spec-group-3">

<h3 id="(with-captures-in-the-pattern)">(with captures in the pattern)</h3>

<h4 id="returns-empty-captures-as-position-matches">returns empty captures as position matches</h4>

<pre class="highlight moonscript"><code><span class="n">matches</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[</span><span class="n">p</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="n">p</span><span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="n">r</span><span class="s1">'()\\pL+'</span><span class="o">\</span><span class="n">gmatch</span><span class="w"> </span><span class="s1">'well hellö there'</span><span class="w"> </span><span class="p">]</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="mi">6</span><span class="p">,</span><span class="w"> </span><span class="mi">12</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="n">matches</span></code></pre>


<h4 id="produces-the-the-set-of-captures-in-each-call">produces the the set of captures in each call</h4>

<pre class="highlight moonscript"><code><span class="n">matches</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="p">[{</span><span class="n">p</span><span class="p">,</span><span class="n">m</span><span class="p">}</span><span class="w"> </span><span class="k">for</span><span class="w"> </span><span class="n">p</span><span class="p">,</span><span class="n">m</span><span class="w"> </span><span class="k">in</span><span class="w"> </span><span class="n">r</span><span class="s1">'()(\\w+)'</span><span class="o">\</span><span class="n">gmatch</span><span class="w"> </span><span class="s1">'well hello there'</span><span class="p">]</span><span class="w">
</span><span class="n">assert</span><span class="p">.</span><span class="n">same</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="p">{</span><span class="mi">1</span><span class="p">,</span><span class="w"> </span><span class="s1">'well'</span><span class="p">},</span><span class="w"> </span><span class="p">{</span><span class="mi">6</span><span class="p">,</span><span class="w"> </span><span class="s1">'hello'</span><span class="p">},</span><span class="w"> </span><span class="p">{</span><span class="mi">12</span><span class="p">,</span><span class="w"> </span><span class="s1">'there'</span><span class="p">}</span><span class="w"> </span><span class="p">},</span><span class="w"> </span><span class="n">matches</span></code></pre>

</div>
</div>
<div class="spec-group spec-group-2">

<h2 id="test(s)">test(s)</h2>

<h4 id="returns-true-if-the-regex-matches-&lt;s&gt;">returns true if the regex matches &lt;s&gt;</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">is_true</span><span class="w"> </span><span class="n">r</span><span class="p">(</span><span class="s1">'ri\\S+'</span><span class="p">)</span><span class="o">\</span><span class="n">test</span><span class="w"> </span><span class="s1">'red right hand'</span></code></pre>


<h4 id="returns-false-if-the-regex-does-not-match-&lt;s&gt;">returns false if the regex does not match &lt;s&gt;</h4>

<pre class="highlight moonscript"><code><span class="n">assert</span><span class="p">.</span><span class="n">is_false</span><span class="w"> </span><span class="n">r</span><span class="p">(</span><span class="s1">'foo'</span><span class="p">)</span><span class="o">\</span><span class="n">test</span><span class="w"> </span><span class="s1">'bar'</span></code></pre>

</div>
</div>
